home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1996 #14 / Monster Media No. 14 (April 1996) (Monster Media, Inc.).ISO / prog_bas / pclvbw10.zip / PCLVBW_U.DOC < prev    next >
Text File  |  1996-02-16  |  69KB  |  2,109 lines
  1.  
  2.  
  3.                  Personal Communications Library
  4.  
  5.                     For Visual BASIC (Windows)
  6.  
  7.  
  8.                            (PCLVBW)
  9.  
  10.  
  11.  
  12.                         USERS MANUAL
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                          Version  1.0
  19.  
  20.                          Feb 11, 1996
  21.  
  22.  
  23.  
  24.  
  25.                This software is provided as-is.
  26.         There are no warranties, expressed or implied.
  27.  
  28.  
  29.  
  30.  
  31.                      Copyright (C) 1996
  32.                      All rights reserved
  33.  
  34.  
  35.  
  36.                      MarshallSoft Computing, Inc.
  37.                      Post Office Box 4543
  38.                      Huntsville AL 35815
  39.  
  40.                      Voice 205-881-4630
  41.                      FAX   205|880|0925
  42.                      BBS   205-880-9748
  43.  
  44.  
  45.                                 _______
  46.                            ____|__     |                (R)
  47.                         --+       |    +-------------------
  48.                           |   ____|__  |  Association of
  49.                           |  |       |_|  Shareware
  50.                           |__|   o   |    Professionals
  51.                         --+--+   |   +---------------------
  52.                              |___|___|    MEMBER
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  PCLVBW Users Manual                                               Page 1
  69.                      C O N T E N T S
  70.  
  71.  
  72.  
  73.  
  74.  
  75.   Chapter                                                   Page
  76.  
  77.   1.0 Introduction................................................3
  78.       1.1 User Support............................................4
  79.       1.2 ASP Ombudsman...........................................4
  80.       1.3 Disabling Windows Ports.................................5
  81.       1.4 Installation............................................6
  82.   2.0 Library Organization........................................7
  83.       2.1 Configuration...........................................7
  84.       2.2 Initialization & Termination............................7
  85.       2.3 Modem Control & Status..................................8
  86.       2.4 Serial I/O..............................................8
  87.       2.5 Error Detection.........................................9
  88.       2.6 General Support.........................................9
  89.   3.0 Library Overview...........................................10
  90.       3.1 Using the Library......................................10
  91.       3.2 Example Programs.......................................10
  92.       3.3 Door Programs..........................................11
  93.       3.4 BBS Programs...........................................11
  94.       3.5 Compiling & Linking....................................11
  95.   4.0 Talking to Your Modem......................................12
  96.       4.1 Modem Standards........................................12
  97.       4.2 Flow Control...........................................13
  98.       4.3 Modem I/O (MIO)........................................14
  99.           4.3.1 MIO Introduction.................................14
  100.           4.3.2 MIO Functions....................................15
  101.                 4.3.2.1 mioDriver................................15
  102.                 4.3.2.2 mioBreak.................................15
  103.                 4.3.2.3 mioSendTo................................15
  104.                 4.3.2.4 mioWaitFor...............................15
  105.                 4.3.2.5 mioQuiet.................................16
  106.           4.4.3 MIO Summary......................................16
  107.       4.4 Modem Initialization...................................17
  108.   5.0 Problems...................................................18
  109.   6.0 Serial Communications......................................19
  110.       6.1 Communications Basics..................................19
  111.       6.2 Standard Port Addresses................................20
  112.       6.3 Running 3 or 4 Ports Concurrently......................21
  113.       6.4 Using Multiport Cards..................................22
  114.           6.4.1 The DigiBoard....................................22
  115.           6.4.2 The BOCA Board...................................22
  116.       6.5 Transmitter Interrupts.................................23
  117.       6.6 RS232 Signals..........................................24
  118.       6.7 National 8250, 6450, and 16550 UARTs...................25
  119.       6.8 Register Summary.......................................26
  120.   7.0 [reserved section number]
  121.   8.0 Legal Issues...............................................28
  122.       8.1 Registration...........................................28
  123.       8.2 License................................................28
  124.       8.3 Warranty...............................................28
  125.   9.0 Summary....................................................30
  126.       9.1 Revision History.......................................30
  127.       9.2 Function Summary.......................................30
  128.       9.3 Further Reading........................................31
  129.  10.0 Other MarshallSoft Computing Products .....................31
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  PCLVBW Users Manual                                               Page 2
  137.   1.0 Introduction
  138.  
  139.  
  140.   The  Personal  Communications Library for Visual BASIC / Windows (PCLVBW) is
  141.   an asynchronous communications library  designed  for  experienced  software
  142.   developers programming in Windows using Visual BASIC.
  143.  
  144.   PCLVBW  controls  the  serial  port  hardware directly.  It does not use the
  145.   Windows serial communications API functions. This allows up to 20 ports with
  146.   a maximum baud rate of 115,200 baud. The PCL features:
  147.  
  148.   o 36 communications and support functions.
  149.   o Supports the high performance 16550 UART.
  150.   o Use IRQ2 to IRQ15 with any UART address.
  151.   o Supports the PC/4 and PC/8 DigiBoard.
  152.   o Supports the BOCA BB1004, BB1008, and BB2016 boards.
  153.   o Supports hardware (RTS/CTS) flow control.
  154.   o Interrupt driven receiver & (optionally) transmitter.
  155.   o Supports 300 baud to 115,200 baud.
  156.   o Supports COM1 through COM8 (through COM20 with multiport boards)
  157.   o Adjustable receive queues from 8 bytes to 32 KB.
  158.   o Control-BREAK error exit.
  159.   o 18 communications error conditions trapped.
  160.   o Allows 4 ports to run concurrently (more with multiport boards).
  161.   o Complete modem control & status.
  162.   o Written in assembly language for small size & high speed.
  163.   o Does NOT use the Windows 3.X communications driver.
  164.  
  165.   Why should you buy PCLVBW ?  Several good reasons are:
  166.  
  167.     COMPLETE - PCLVBW is complete since it provides absolute  control  of  the
  168.                serial ports (including the high performance 16550).
  169.  
  170.      COMPACT - PCLVBW  is  very  compact at less than 8 KB.  Your application
  171.                doesn't carry a lot of excess code.
  172.  
  173.         FAST - PCLVBW is fast since it runs at 38400 baud on even slow 286
  174.                PCs and at 115200 baud on most everything else.
  175.  
  176.      SUPPORT - If you get stuck, you talk to the  programmer  that  wrote the
  177.                code, not a person hired to answer the phone.
  178.  
  179.         BBS  - A BBS is available (2400 to 14,400  baud,  N81)  in  order  to
  180.                provide immediate support as necessary.
  181.  
  182.   NEWSLETTER - Our newsletter discusses "COMM  TALK"  is  published  quarterly
  183.                (available  online) which discusses communications problems and
  184.                solutions.
  185.  
  186.        PRICE - You get PCLVBW for a very reasonable price!
  187.  
  188.     UPGRADES - Once you buy PCLVBW, you can always update to  the  most recent
  189.                version very inexpensively ($20 plus shipping).
  190.  
  191.   Be  sure  to  read  the  README.DOC file. It contains last release notes and
  192.   other last minutes changes and/or additions.
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  PCLVBW Users Manual                                               Page 3
  205.   1.1 User Support
  206.  
  207.  
  208.   We want you to be successful in developing your applications  using  PCLVBW!
  209.   We depend on our customers to let us know what they need in a communications
  210.   library.   This  means we are committed to providing the best communications
  211.   library that we can. If you have any suggestions or comments, please let  us
  212.   know!
  213.  
  214.   We  provide  customer  support  for registered customers by voice, FAX, BBS,
  215.   email, and US mail.  We provide limited support for  unregistered  users  by
  216.   voice, email, and BBS only.
  217.  
  218.   If  you  are  having a problem using PCLVBW, call us at 205-881-4630 between
  219.   1:30 PM and 9:30 PM (CST) Monday through Friday. You can also call at  other
  220.   times and leave a message, and call back later for a reply. Registered users
  221.   (ONLY) can also FAX us at 205-880-0925 at any time (24 hours).
  222.  
  223.   However,  we  can  only  answer  questions  with respect to using the PCLVBW
  224.   library.  We cannot help you program your application, but we'll be glad  to
  225.   discuss it with you.
  226.  
  227.   You  may  also  call  our User Support BBS (2400 to 14400 baud, no parity, 8
  228.   data bits, 1 stop bit) at 205-880-9748 and leave a message  (address  it  to
  229.   the SYSOP).  We will usually have a reply ready for you within 24 hours.
  230.  
  231.   The BBS is available 24 hours per day. All files are in standard ZIP format.
  232.   The BBS will contain  the  latest  shareware  version  of  all  MarshallSoft
  233.   Computing products as well as related files such as:
  234.  
  235.       BUGS.ZIP     -  Bug report.
  236.       PRODUCTS.ZIP -  List of all shareware products.
  237.  
  238.   The  MarshallSoft  Computing,  Inc.   newsletter  "Comm  Talk"  is published
  239.   quarterly.  It discusses various communications problems and solutions using
  240.   PCLVBW as well as related information.
  241.  
  242.   The latest copy of our newsletter can be found on our support BBS, anonymous
  243.   FTP site, or on our Web site.
  244.  
  245.       BBS      : 205-880-9748            (look in file area "Newsletters")
  246.       Anon FTP : ftp.traveller.com       (directory  /pub/users/msc)
  247.       Web site : www.traveller.com/~msc/
  248.  
  249.  
  250.   1.2 ASP Ombudsman
  251.  
  252.  
  253.   MarshallSoft  Computing,  Inc.   is a member of the Association of Shareware
  254.   Professionals (ASP).  ASP wants to make sure that  the  shareware  principle
  255.   works  for  you.   If  you are unable to resolve a shareware-related problem
  256.   with an ASP member by contacting the member directly, ASP  may  be  able  to
  257.   help.  The  ASP  Ombudsman can help you resolve a dispute or problem with an
  258.   ASP member, but does not provide technical support  for  members'  products.
  259.   Please  write  to  the  ASP  Ombudsman  at 545 Grover Road, Muskegon, MI USA
  260.   49442-9427, Fax 616-788-2765, or send a CompuServe  message  via  CompuServe
  261.   Mail to ASP Ombudsman 70007,3536.
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  PCLVBW Users Manual                                               Page 4
  273.   1.3 Disabling Windows Ports
  274.  
  275.  
  276.   The  Windows operating system virtualizes all serial ports that it controls.
  277.   This  means  that  Windows  intercepts  reads  and writes to hardware ports,
  278.   resulting in significan slowdown. And, when Windows virtualizes a port,  the
  279.   UART FIFO control register (FCR) can not be modified.
  280.  
  281.   Since PCLVBW also controls the hardware directly, it is best  (although  not
  282.   absolutely necessary) to disable Windows control of the serial ports and the
  283.   IRQs that will be used by PCLVBW applications.
  284.  
  285.   To find which ports Windows wants to control, choose the "386 Enhanced" icon
  286.   in the "Control Panel" in the "Main Group" when running Windows.
  287.  
  288.   The four standard COM ports which Windows typically controls are:
  289.  
  290.       Port  Address  IRQ
  291.       COM1   &H3F8    4
  292.       COM2   &H2F8    3
  293.       COM3   &H3E8    4
  294.       COM4   &H2E8    3
  295.  
  296.   Since COM1 and COM3 share an IRQ, if either is to be  used  by  PCLVBW  then
  297.   both should be disabled from Windows control. Similarly for COM2 and COM4.
  298.  
  299.   To begin, exit from Windows completely. To disable the  serial  ports,  edit
  300.   the  [386Enh] section of the WINDOWS.INI file in the WINDOWS directory.  For
  301.   example, to disable COM1 and COM3,  add  the  following  to  the  [386  Ehn]
  302.   section:
  303.  
  304.       COM1Base=0
  305.       COM1Irq=-1
  306.       COM3Base=0
  307.       COM3Irq=-1
  308.  
  309.   After modifying SYSTEM.INI, Windows must be restarted (type WIN).
  310.  
  311.   The  above  procedure does not apply to multiport boards or any serial ports
  312.   that Windows does not know about.
  313.  
  314.   16550 UARTS are really necessary when running under Windows, particularly at
  315.   baud  rate  above  9600.  The Microsoft Diagnostics (MSD) program can be run
  316.   which will report the type of UARTs installed on your machine.
  317.  
  318.   If  a 16550 port MUST be shared with Windows, and you want the FIFO enabled,
  319.   look for statements such as
  320.  
  321.       COM1FIFO=0
  322.  
  323.   in the [386Ehn] section of SYSTEM.INI and delete it.  However,  the  Windows
  324.   communications  driver may have trouble with the FIFO, which is why there is
  325.   a statement to disable it. This problem does not occur with PCLVBW.
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  PCLVBW Users Manual                                               Page 5
  341.   1.4 Installation
  342.  
  343.  
  344.   (1) Before installation of PCLVBW, your Visual BASIC compiler should already
  345.   be installed on your system and tested. It is recommended that  you  disable
  346.   Windows's  control  of  the  serial  ports  that you will be using. Refer to
  347.   section 1.3 "Disabling Windows Ports".
  348.  
  349.   (2) Make a backup  copy  of  your  distribution  disk.   Put  your  original
  350.   distribution disk in a safe place.
  351.  
  352.   (3) Create a work directory on your work disk (normally your harddisk).  For
  353.   example, to create a work directory named PCLVBW, we first log onto the work
  354.   disk and then type:
  355.  
  356.                    MKDIR PCLVBW
  357.  
  358.   (4)  Copy  all  the  files from your backup copy of the distribution disk to
  359.   your work directory.  For example, to copy from the A: drive  to  your  work
  360.   directory, we type:
  361.  
  362.                   CD PCLVBW
  363.                   COPY A:*.*
  364.  
  365.   (5)  Copy  the  DLL  (dynamic link libraries) PCLVBW.DLL and MIO.DLL and the
  366.   icon file MSC.ICO, to the directory from which Visual Basic is running. This
  367.   is the directory reported by selecting FILES, and  then  PROPERTIES  on  the
  368.   Windows menu bar after clicking (once) on the Visual Basic icon.
  369.  
  370.   (6)  Start  Visual  Basic,  and  load  the SIMPLE example program by opening
  371.   project SIMPLE.MAK. It can then be run by choosing RUN on the  Visual  Basic
  372.   menu bar.  If Visual Basic cannot load the DLLs, it means that they have not
  373.   been copied into the Visual Basic directory as outlined in (5) above.
  374.  
  375.   (7) Also load and compile LOGIN.
  376.  
  377.   (8)  The  easiest way to test SIMPLE is to run it on two computers connected
  378.   by a null modem  cable.   Whatever  is  typed  on  one  computer  should  be
  379.   displayed on the other. SIMPLE can also be tested by connecting your port to
  380.   a modem.
  381.  
  382.   (9)    LOGIN   can   be   tested   by   connecting   to   a   modem.   Select
  383.   MODEM/START/HANDSHAKE on the dial menu bar to send an AT  to  the  connected
  384.   modem.  An  "OK" is expected in return. Selecting MODEM/START/DIAL will dial
  385.   the MarshallSoft Computing BBS.
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  PCLVBW Users Manual                                               Page 6
  409.   2.0 Library Organization
  410.  
  411.  
  412.   The PCLVBW library is organized into six categories of functions.  Refer  to
  413.   the PCL Reference Manual (PCLVBW.REF) for details on individual functions.
  414.  
  415.  
  416.   2.1 Configuration
  417.  
  418.  
  419.   There are three functions in the configuration category.  SioPorts sets the
  420.   number  of PC and DigiBoard (or BOCA board) ports. SioUART is used to change
  421.   the UART base address for a communications port to a  non-standard  address,
  422.   while  SioIRQ  is  used  to  assign  a nonstandard IRQ line to a port.  (See
  423.   chapter 6 Serial Communications for more details on standard UART  addresses
  424.   and IRQ lines).
  425.  
  426.   The  configuration  functions  SioPorts,  SioUART  and SioIRQ must be called
  427.   before calling any other library functions.  Be very careful in using  these
  428.   functions.  Remember that your serial hardware must support the UART and IRQ
  429.   that you specify.  Always test any new configuration immediately.
  430.  
  431.   SioPorts -  Sets number of PC and DigiBoard (or BOCA board) ports.
  432.   SioUART  |  Sets the UART base address.
  433.   SioIRQ   -  Assigns an IRQ line to a port.
  434.  
  435.   THE  IRQ  GOLDEN  RULE:  You  may  open (via SioReset) only one port per IRQ
  436.   (except for the DigiBoard and BOCA board).
  437.  
  438.   Be  sure  to read section 1.3 "Disabling Windows Ports" since it is best not
  439.   to share ports with Windows.
  440.  
  441.  
  442.   2.2 Initialization & Termination
  443.  
  444.  
  445.   There are eight functions in the initialization  and  termination  category.
  446.   Together,  SioParms,  SioFIFO,  SioRxBuf,  SioTxBuf, and SioReset initialize
  447.   your serial communications system.  Your application must call SioParms  and
  448.   SioRxBuf  before  calling  SioReset,  and SioReset must be called before any
  449.   serial I/O processing can be done.
  450.  
  451.   After initialization, SioParms and SioBaud can be called again to change the
  452.   communications parameters without resetting the serial port. SioFlow can  be
  453.   called to enable hardware flow control.
  454.  
  455.   Before  exiting  from  your  application, SioDone must be called. Failure to
  456.   call SioDone can crash your system later.
  457.  
  458.   SioRxBuf   - Sets up receive buffer.
  459.   SioTxBuf   | Sets up transmitter buffer.
  460.   SioFIFO    | Sets the interrupt level for the 16550.
  461.   SioParms   | Sets parity, stop bits, and word length.
  462.   SioReset   | Initialize a serial port for processing.
  463.   SioDone    | Terminates further serial processing.
  464.   SioBaud    | Sets the baud rate of the selected port.
  465.   SioFlow    - Enables / disables flow control.
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  PCLVBW Users Manual                                               Page 7
  477.   2.3 Modem Control & Status
  478.  
  479.  
  480.   There are nine functions in the modem  control  and  status  category  which
  481.   provide  your  application with complete control over the status and control
  482.   bits of your modem.
  483.  
  484.   There are two modem control bits, "Data Terminal Ready" (DTR)  and  "Request
  485.   To  Send"  (RTS).   These  bits  can  be read, set, or cleared by SioDTR and
  486.   SioRTS.
  487.  
  488.   There are four modem status bits, "Data Set Ready" (DSR),  "Clear  To  Send"
  489.   (CTS),  "Ring Indicator" (RI), and "Data Carrier Detect" (DCD). SioModem can
  490.   read any of the modem status bits.  SioDSR, SioCTS, SioRI,  and  SioDCD  can
  491.   only  read  their respective modem status bit. SioGetDiv reads the baud rate
  492.   divisor register so the baud rate can be determined.
  493.  
  494.   Refer to the chapter entitled "RS232 Signals" for a discussion  of  each  of
  495.   the control and status bits.
  496.  
  497.   SioDTR    - Set, clear, or read the Data Terminal Ready (DTR) bit.
  498.   SioRTS    | Sets, clears, or reads the Request to Send (RTS) line.
  499.   SioModem  | Reads the modem status register.
  500.   SioDSR    | Reads the Data Set Ready (DSR) modem status bit.
  501.   SioCTS    | Reads the Clear to Send (CTS) modem status bit
  502.   SioDCD    | Reads the Data Carrier Detect (DCD) modem status bit.
  503.   SioRI     | Reads the Ring Indicator (RI) modem status bit.
  504.   SioRead   | Reads the contents of the 7 UART registers.
  505.   SioGetDiv - Reads the baud rate divisor registers.
  506.  
  507.  
  508.   2.4 Serial I/O
  509.  
  510.  
  511.   There are eleven library functions in the serial  I/O  category.   Together,
  512.   these functions give the programmer complete control over serial I/O. Higher
  513.   level  functions  such  as  protocols  and smart modem communications can be
  514.   completely implemented in terms of these functions.  Refer  to  the  example
  515.   code.
  516.  
  517.   SioGetc  and  SioPutc  read  and  write  single  bytes from the serial line.
  518.   SioPuts and SioGets read and write blocks of characters. SioUnGetc  "ungets"
  519.   the  last  serial  byte  read.   SioRxClear  clears  the receive queue while
  520.   SioTxClear clears the transmit queue. SioLine can be used to test  for  UART
  521.   errors.   SioTxFlush  completes  transmission  of  all bytes in the transmit
  522.   buffer before returning.  SioRxQue  returns  the  number  of  bytes  in  the
  523.   receive  queue  while  SioTxQue  returns the number of bytes in the transmit
  524.   queue.
  525.  
  526.   SioGetc    - Reads the next character from the serial line.
  527.   SioGets    | Reads a block of characters from the serial line.
  528.   SioPutc    | Transmit a character over a serial line.
  529.   SioPuts    | Transmit a block of characters over a serial line.
  530.   SioUnGetc  | "Un-gets" (puts back) a specified character.
  531.   SioRxClear | Clears the receive  buffer.
  532.   SioRxQue   | Returns the number of characters in the RX queue.
  533.   SioTxClear | Clears the transmit buffer.
  534.   SioTxFlush | Flushes the transmit buffer.
  535.   SioTxQue   | Returns the number of characters in the TX queue.
  536.   SioLine    - Reads the line status register.
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  PCLVBW Users Manual                                               Page 8
  545.   2.5  Error Detection
  546.  
  547.  
  548.   There  are two functions in the error detection category. They are concerned
  549.   with detecting or reporting communications errors.  Use of  these  functions
  550.   can make your application significantly more robust.
  551.  
  552.   SioBrkSig can read or modify  the  UART  break  bit.   This  is  useful  for
  553.   signalling   the   remote  system  that  a  fatal  condition  has  occurred.
  554.   SioLoopBack can be used to  test  the  integrity  of  your  UART.
  555.  
  556.   SioBrkSig   - Asserts, cancels, or detects the RS232 BREAK  signal.
  557.   SioLoopBack - Performs a UART loopback test.
  558.  
  559.  
  560.   2.6 General Support
  561.  
  562.  
  563.   There  is  just  one  functions  in  the  general  support category. SioInfo
  564.   returns a host of information, such  as  the  PCLVBW  library  version,  the
  565.   number of transmitter and receiver interrupts, etc.
  566.  
  567.   SioInfo     - Returns the library version, and various other info.
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  PCLVBW Users Manual                                               Page 9
  613.   3.0 Library Organization
  614.  
  615.  
  616.   3.1 Using the Library
  617.  
  618.  
  619.   Please  examine the PCLVBW.BAS file. Note that COM1 is defined as port zero,
  620.   not port one.  The user  must  assume  the  responsibilty  for  passing  the
  621.   correct information when calling PCLVBW functions.
  622.  
  623.   If there are any conflicts between PCLVBW definitions  and  those  in  other
  624.   libraries,  the  PCLVBW definitions can be changed in the PCLVBW.BI file and
  625.   any file that uses the definition. There is  no  change  necessary  for  the
  626.   library code itself.
  627.  
  628.   The  PCLVBW  libraries contain no references to any runtime libraries.  Only
  629.   Windows API functions are called.
  630.  
  631.  
  632.   3.2 Example Programs
  633.  
  634.  
  635.   Two  communications  programs are provided as a demonstration of the PCLVBW
  636.   library - SIMPLE and LOGIN.
  637.  
  638.   SIMPLE is a very simple communications programming using PCLVBW.  Everything
  639.   that  is  typed  on  the  keyboard is sent to the serial port, and everthing
  640.   incoming from the serial port is displayed on the screen.
  641.  
  642.   Load  SIMPLE.MAK  from  Visual  Basic.  Select "Change" from the menu bar to
  643.   change the port, baud  rate,  parity,  data  bits,  or  stop  bits.   Select
  644.   "OnLine" from the "Line" menu item to go online.
  645.  
  646.   Test  SIMPLE  by  connecting  the port it controls to a modem and issuing AT
  647.   commands, or connect to another computer using a null modem cable.
  648.  
  649.   LOGIN is the same program as SIMPLE but with the addition of "Modem" on  the
  650.   menu  bar.  Under "Modem", select "Start", then "Handshake" in order to send
  651.   an "AT" to the connected modem, or "Dial" to  send  a  dial  string  to  the
  652.   modem  (which  dials  our user support BBS). Once the dial sequence is sent,
  653.   the program will wait for up to 60 seconds for the "CONNECT" string from the
  654.   modem. This wait can be terminated at any time  by  choosing  "BREAK"  under
  655.   "Modem".
  656.  
  657.   LOGIN serves as an example of the use of the MIO.BAS (modem I/O)  functions.
  658.   Refer to section 4.3 "Modem I/O" for more information on MIO functions.
  659.  
  660.   To  test LOGIN, you need a AT command set compatible modem and a BBS to call
  661.   up. LOGIN will dial our BBS at 205-880-9748, or  edit  the  dial  string  in
  662.   LOGLINE.BAS to call up a local BBS.
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.  
  673.  
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  PCLVBW Users Manual                                               Page 10
  681.   3.3 Door Programs
  682.  
  683.  
  684.   In  order  to  write a door program which "takes over" a serial port without
  685.   resetting the port or changing the baud rate, call SioReset()  with  NORESET
  686.   as  the  second  argument rather than the baud rate. Call SioGetDiv() to get
  687.   the baud rate divisor if the baud rate must be determined. Be sure  to  call
  688.   SioDone() before returning to the invoking program.
  689.  
  690.  
  691.   3.4 BBS Programs
  692.  
  693.  
  694.   If you are designing a BBS program (also known as HOST  programs),  consider
  695.   using  16550  UARTS.   You  should  also choose a multiport card such as the
  696.   DigiBoard or BOCA board if you wish to run more than 4 ports simultaneously.
  697.  
  698.   If  you  are using an error correcting modem, then you should be sure to set
  699.   flow control and fix your baud rate at the highest possible transfer  rates.
  700.   For  14,400  modems, this means 19200 or 38400. You may need a 16550 UART in
  701.   order to run at the higher speed.
  702.  
  703.   If you are using an older multi-speed modem (say  1200,  2400,  4800,  9600)
  704.   that doesn't use flow control, you should change your baud rate to match the
  705.   baud rate as reported by the modem with the CONNECT message if necessary.
  706.  
  707.   3.5 Compiling and Linking
  708.  
  709.  
  710.   Registered users may wish to recreate PCLVBW.DLL.  The Microsoft  assembler
  711.   (MASM) and the Microsoft C compiler are required. Type
  712.  
  713.       NMAKE PCL4W.MAK
  714.       RENAME PCL4W.DLL PCLVBW.DLL
  715.  
  716.   Similiarly, MIO.DLL can be recreated.
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  PCLVBW Users Manual                                               Page 11
  749.   4.0 Talking to Your Modem
  750.  
  751.  
  752.   A modem is used to extend the  distance  over  which  you  may  communicate.
  753.   Without  a  modem, your RS232 cable is limited to a maximum of approximately
  754.   50 feet.  But with a modem, you can communicate literally around the world.
  755.  
  756.   Also  refer  to  Section  4.3  "MODEM I/O  functions" for details on MODEM I/O
  757.   functions. These functions faciliate communications with modems.
  758.  
  759.  
  760.   4.1 Modem Standards
  761.  
  762.  
  763.   Two modems can communicate over a telephone line only if they are both using
  764.   the  same  signaling frequencies and modulation, which are determined by the
  765.   the modem standards used.  Modem standards can be divided into  three  sets:
  766.   (1) speed, (2) data compression used, and (3) error control.
  767.  
  768.   The  Bell  standards  (103  &  212A)  are  those  of  AT&T.   The CCITT (The
  769.   International Consultative Committee for Telephone and Telegraph)  standards
  770.   are designated as "V. ".
  771.  
  772.  
  773.   Speed
  774.  
  775.  
  776.   Bell 103  -   300 baud
  777.   Bell 212A |  1200 baud
  778.   V.21      |   300 baud
  779.   V.22bis   |  1200 & 2400 baud
  780.   V.32      |  4800 & 9600 baud
  781.   V.32bis   |  4800, 7200, 9600, 12000, and 14400 baud
  782.   V.34      -  28800 baud.
  783.  
  784.   Data Compression
  785.  
  786.  
  787.   MNP 5     -  Microcom Networking Protocol (proprietary).
  788.   V.42bis   -  International data compression standard.
  789.  
  790.  
  791.   Error Control
  792.  
  793.  
  794.   MNP 2,3,4 -  Three level error correction (public domain).
  795.   V.42      -  International error correction standard.
  796.  
  797.  
  798.   Most of the newer high speed modems use  several  of  the  above  standards.
  799.   However,  not  all  combinations of modem makes communicate easily with each
  800.   other, especially at high speeds (9600 and up).
  801.  
  802.  
  803.  
  804.  
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  PCLVBW Users Manual                                               Page 12
  817.   4.2 Flow Control
  818.  
  819.  
  820.   With modems using data compression, the modem to modem connection  will  run
  821.   at  various  speeds  depending  on the quality of the line.  The computer to
  822.   modem connection will be at a fixed baud rate. Therefore, a  protocol  (flow
  823.   control)  is  necessary to synchronize the data flow between a modem and the
  824.   computer to  which  it  is  connected.   Refer  to  your  modem  manual  for
  825.   information on flow control protocols supported.
  826.  
  827.   Two flow control protocols are used by most all modems  which  require  flow
  828.   control.   Software  flow  control is called "XON/XOFF" (other software flow
  829.   control character pairs are defined but operate the same  as  XON/XOFF)  and
  830.   hardware  flow  control is called "RTS/CTS".  Most modems which require flow
  831.   control enable hardware flow control by default.
  832.  
  833.   In XON/XOFF (software) flow control, the computer suspends transmitting data
  834.   if it receives a XOFF character (13  hex)  from  the  modem,  and  continues
  835.   transmitting  when  it  receives  a XON character (11 hex).  Similiarly, the
  836.   computer can signal the modem not to send any more data  by  transmitting  a
  837.   XOFF  to  it,  and  can tell the modem to continue transmission be sending a
  838.   XON.
  839.  
  840.   In RTS/CTS (hardware) flow control, the RTS line is used by the computer  to
  841.   signal  the  modem  ,  while the CTS line is used by the modem to signal the
  842.   computer.  The RTS line is set OFF by the computer  to  tell  the  modem  to
  843.   suspend  transmission,  and  set  to  ON  to  tell  the  modem  to  continue
  844.   transmission.  The CTS line is set to OFF by the modem to tell the  computer
  845.   to  stop  transmitting,  and  set  to  ON  to  tell the computer to continue
  846.   transmitting.
  847.  
  848.   Given the choice, always choose hardware flow  control  over  software  flow
  849.   control  so  that  all  data  transmission is transparent.  If hardware flow
  850.   control is not the default (which it almost always is),  you  should  modify
  851.   your modem initialization string to turn hardware flow control on.
  852.  
  853.   You will not need to use flow control when exchanging data between computers
  854.   connected  by  a  null  modem  cable  (no  modems) as long as each packet is
  855.   acknowledged (as in XMODEM and YMODEM) and the buffer size is  at  least  as
  856.   large as the packet size.
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  PCLVBW Users Manual                                               Page 13
  885.   4.3 MODEM I/O (MIO)
  886.  
  887.   4.3.1 MIO Introduction
  888.  
  889.   The file MIO.BAS contains declarations for using the Modem I/O  DLL.   These
  890.   functions  ease  communicating  with  modems  using  AT  commands. The LOGIN
  891.   example program code has examples of using the MIO functions.
  892.  
  893.   The   Windows   3.X  "operating  system"  is  what  is  called  "cooperative
  894.   multitasking". This means that the executing Windows task  must  voluntarily
  895.   "give  up"  control  before  another  Windows  task  (or Windows itself) can
  896.   execute.
  897.  
  898.   The  difficulty  is  how  to  wait  for  a  number  of  seconds  while still
  899.   relinquishing control periodically before the wait is up. One solution is by
  900.   making functions that need to wait (such as the MIO functions) into  "state"
  901.   machines. A function is broken down into parts called states, and control is
  902.   returned to Windows between executing each state.
  903.  
  904.   For  example,  to  send  the string "ATDT1,205,880,9748" to the  modem  with
  905.   one  tenth  second  delay  between  transmitted  characters,  the  following
  906.   sequence is used:
  907.  
  908.   (1) Send the string to the MIO driver by executing:
  909.  
  910.          Code = mioSendTo(Port,100,"!ATDT1,205,880,9748")
  911.  
  912.   The '!' characters are converted to carriage returns.  The  text  string  is
  913.   copied into the driver's data area.
  914.  
  915.   (2)  Call mioDriver (typically based on a Visual BASIC timer) until MIO_IDLE
  916.   is returned.  Each time mioDriver is called, it will send another  character
  917.   to  the  modem provided the required delay (since the previous character was
  918.   sent) has passed.  If the delay has not passed, the  driver  simply  returns
  919.   MIO_RUNNING,  but  without  actually sending a character to the modem.  Once
  920.   all characters have been sent, mioDriver will return MIO_IDLE, indicating it
  921.   is done and is ready to accept another function.
  922.  
  923.   mioDriver will return MIO_RUNNING if it is still processing.  Anything  else
  924.   received  indicates  that it is still processing and the returned value is a
  925.   character from the modem that can be displayed if wanted.
  926.  
  927.   (3) Once mioDriver returns MIO_IDLE, call mioResult to get the result of the
  928.   mioSendTo call.
  929.  
  930.   The above is rather straight forward in practice.  See the LOGIN application
  931.   for an example of its use.
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  PCLVBW Users Manual                                               Page 14
  953.   4.3.2 MIO Functions
  954.  
  955.  
  956.   4.3.2.1 mioDriver
  957.  
  958.   Syntax: mioDriver(ByVal Port As Integer) As Integer
  959.  
  960.   mioDriver  executes  the  next  state of any previously started MIO function
  961.   such as mioSendTo, mioWaitFor, and mioQuiet. It returns:
  962.  
  963.   MIO_IDLE    : if the driver is ready for the next mioSendTo, mioWaitFor, or
  964.                 mioQuiet.
  965.   MIO_RUNNING : if the driver is not idle.
  966.   <otherwise> : if the driver is not idle,  and  the  returned  character  was
  967.                 received from the modem.
  968.  
  969.  
  970.   4.3.2.2 mioBreak
  971.  
  972.   Forces the MIO driver to the IDLE state, abandoning any work in progress.
  973.  
  974.  
  975.   4.3.2.3 mioSendTo
  976.  
  977.   Syntax:  FUNCTION mioSendTo(ByVal Port As Integer,
  978.                               ByVal Pace As Long,
  979.                               ByVal Text As STRING) As Integer
  980.  
  981.   The mioSendTo function sends the characters in the string 'Text'  to  serial
  982.   output. There is a delay of 'Pace' milliseconds between characters.
  983.  
  984.  
  985.   4.3.2.4 mioWaitFor
  986.  
  987.   Syntax: FUNCTION mioWaitFor(ByVal Port As Integer,
  988.                               ByVal Wait As Long,
  989.                               ByVal Case As Integer,
  990.                               ByVal Text As String) As Integer
  991.  
  992.   The mioWaitFor function waits for characters from serial  input  that  match
  993.   the  string 'Text'. A total of 'Wait' milliseconds are allowed before timing
  994.   out and returning FALSE (0).  If the 'Case' flag is TRUE,  then  the  string
  995.   comparison is NOT case sensitive.
  996.  
  997.   For  example,  to  wait  up  to  one  minute for "CONNECT", "NO CARRIER", or
  998.   "BUSY" from the modem after dialing a number (on COM1):
  999.  
  1000.       Code = mioWaitFor(COM1,60000,1,"CONNECT|NO CARRIER|BUSY")
  1001.  
  1002.   The  function  mioDriver()  must be called until MIO_IDLE is returned.  Then
  1003.   mioResult() is called to get the result of the mioWaitFor.   A  value  of  0
  1004.   indicates that neither "CONNECT", "BUSY", nor "NO CARRIER" was received. A A
  1005.   non-zero  value  indicates that one of the three sub-strings was received. A
  1006.   ASC("0") is returned if "CONNECT" was seen,  ASC("1")  is  returned  if  "NO
  1007.   CARRIER" was seen, and ASC("2") is returned if "BUSY" was seen.
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  PCLVBW Users Manual                                               Page 15
  1021.   4.3.2.5 mioQuiet
  1022.  
  1023.   Syntax: FUNCTION mioQuiet(Port,Wait As Long)
  1024.  
  1025.   The mioQuiet function waits for continuous quiet [no incoming  serial  data]
  1026.   of  'Wait'  milliseconds  before  returning.  Any  incoming  character while
  1027.   mioQuiet us running is flushed.
  1028.  
  1029.  
  1030.   4.3.3 MIO Summary
  1031.  
  1032.       mioDriver   : Allows  the  execution  of  mioSendTo,  mioWaitFor, or
  1033.                     mioQuiet once they have been  started.  Returns  MIO_IDLE
  1034.                     (defined in MIO.BAS) if ready not running, MIO_RUNNING if
  1035.                     running,  and anything else is a character from the modem
  1036.                     that can be displayed if wanted.
  1037.       mioBreak    : Forces the MIO driver to IDLE state.
  1038.       mioSendTo   : Sends string (including control chars) to the modem.
  1039.       mioWaitFor  : Waits for a particular string from the modem, passing
  1040.                     all else through.
  1041.       mioQuiet    : Waits for continuous quiet of specified duration.
  1042.       mioBreak    : Breaks further modem I/O activity.
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.  
  1065.  
  1066.  
  1067.  
  1068.  
  1069.  
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  PCLVBW Users Manual                                               Page 16
  1089.   4.4 Modem Initialization
  1090.  
  1091.  
  1092.   If  your  application uses a modem (as opposed to using a null modem cable),
  1093.   then you should always send an initialization string to your modem if it  is
  1094.   a  programmable  modem  such as those made by Hayes.  Communication programs
  1095.   such as PROCOMM and TELIX always send such a string automatically as soon as
  1096.   they start up.
  1097.  
  1098.   The particular initialization string depends on the make of your modem.  For
  1099.   Hayes and Hayes AT command  set  compatible  modems,  the  following  string
  1100.   (followed by a carriage return) may work:
  1101.  
  1102.        AT E1 S7=60 S11=60 V1 X1 Q0 S0=0
  1103.  
  1104.   Refer to your Modem User's Guide for a full discussion of these commands.  A
  1105.   brief description is as follows:
  1106.  
  1107.   AT     Modem attention command.
  1108.   E1     Modem will echo what you send to it.
  1109.   S7=60  Wait 60 seconds for carrier and/or dial tone.
  1110.   S11=60 Use 60 milliseconds for tone dialing duration & spacing.
  1111.   V1     Display result code as words (not numbers).
  1112.   X1     Use the extended result message (CONNECT XXXX) set.
  1113.   Q0     Modem returns result codes.
  1114.   S0=0   Do not answer RING.
  1115.  
  1116.   If  your application will answer incoming calls, then set the S0 register to
  1117.   the ring on which to automatically answer.
  1118.  
  1119.   If you send the above codes by using SioPutc (as opposed to typing them from
  1120.   the keyboard), then follow these guidelines:
  1121.  
  1122.   (1) Send an initial carriage return before the initialization string.
  1123.  
  1124.   (2) Pause at least a  tenth  of  a  second  (100  milliseconds)  after  each
  1125.   character  sent  as  your  modem  needs the time to perform its own internal
  1126.   processing. Pause a little longer  if  your  modem  is  not  accepting  your
  1127.   initialization string.
  1128.  
  1129.   (3)  Pause  one  and a half seconds after sending any initialization command
  1130.   such as ATZ or AT&F since your modem must do quite a bit of processing.
  1131.  
  1132.   If you experience any problems in initializing your Hayes modem, you  should
  1133.   first reset it to factory settings by sending:
  1134.  
  1135.        AT&F
  1136.  
  1137.   Your modem may require additional initialization than presented above. Refer
  1138.   to your modem manual for details. It you have a comm program such as ProComm
  1139.   or Telix that is known to initialize your modem correctly, then you may wish
  1140.   to use the same initialization string.
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  PCLVBW Users Manual                                               Page 17
  1157.   5.0 Problems
  1158.  
  1159.  
  1160.   If you cannot get your application to run properly, first  compile  and  run
  1161.   the  example programs SIMPLE and LOGIN. Both SIMPLE and LOGIN can be used to
  1162.   call up any BBS.
  1163.  
  1164.   If  your  application  does not run but SIMPLE runs correctly, then you have
  1165.   most likely made a programming mistake in  your  application.   MarshallSoft
  1166.   Computing  cannot  debug  your  application,  especially over the telephone!
  1167.   However, consider each of the following when searching for an error in  your
  1168.   application.
  1169.  
  1170.   1.   Are  you  connected  to a device that requires flow control? Be sure to
  1171.   turn on flow control with SioFlow if connected to a modem  or  other  serial
  1172.   device that uses flow control.
  1173.  
  1174.   2.  Loosing  data  at  high  baud  rates? Turn on port FIFOs with SioFIFO if
  1175.   16550 UARTS are being used. Also disable Windows control of the serial ports
  1176.   you are using. See section 1.3 "Disabling Windows Ports".
  1177.  
  1178.   3.  Is your receive buffer large enough? In  general,  your  receive  buffer
  1179.   should be twice as large as the largest incoming block of data.
  1180.  
  1181.   4.   If you are running two COM ports simultaneously, are you using separate
  1182.   transmit and receive buffers? (you should).
  1183.  
  1184.   5.  Did SioReset return a zero value?  If not, then you must call  SioReset
  1185.   again.
  1186.  
  1187.   6.  Did you send the proper initialization string to your modem? See section
  1188.   4.4 "Modem Initialization".
  1189.  
  1190.   7.  Did you set DTR and RTS? Most serial devices require  that  DTR  be  set
  1191.   before they will respond.
  1192.  
  1193.   8.  Do you have more than one COM1 port, etc.  For example, if  you  have  a
  1194.   COM1  port  on  your  motherboard, you cannot add another COM1 port or modem
  1195.   board that uses COM1 without first disabling COM1 on the motherboard.
  1196.  
  1197.   9.  Are you passing the proper segment of the receive (or transmit) buffer?
  1198.   See SIMPLE or LOGIN for an example.
  1199.  
  1200.   Registered  users  can  call 205-881-4630 from 1:30 PM to 9:30 PM CST Monday
  1201.   through Friday for help.
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  PCLVBW Users Manual                                               Page 18
  1225.   6.0 Serial Communications
  1226.  
  1227.  
  1228.   6.1 Communications Basics
  1229.  
  1230.  
  1231.   The heart of serial  communications  is  the  UART  (Universal  Asynchronous
  1232.   Receiver  Transmitter).   The  IBM  PC/XT/AT  and  compatibles use the 8250,
  1233.   16450, or the 16550 UART.  The purpose of the UART is:
  1234.  
  1235.   (1) To convert bytes from the CPU (Central Processing Unit), into  a  serial
  1236.   format  by  adding  the  necessary start, stop, and parity bits to each byte
  1237.   before transmission, and to then transmit each bit at the correct baud rate.
  1238.  
  1239.   (2) To convert the incoming stream (at a specified baud rate) of serial bits
  1240.   into bytes by removing the start, stop, and parity bits  before  being  made
  1241.   available to the CPU.
  1242.  
  1243.   The  UART  is part of the serial interface circuitry which allows the CPU to
  1244.   send and receive signals over the RS232 lines. This  can  be  diagrammed  as
  1245.   follows:
  1246.  
  1247.  
  1248.                         Serial Interface
  1249.                      +-------------------+
  1250.                      |                   |
  1251.   +-----+  Data Bus  |     +------+      |    RS232 Signals
  1252.   | CPU +------------+     | UART |      +----------------*
  1253.   +-----+            |     +------+      |
  1254.                      |                   |
  1255.                      +-------------------+
  1256.  
  1257.  
  1258.   The  8250/16450/16550  UART  is  capable  of  operating in one of two modes,
  1259.   "polled" and "interrupt driven".  The serial communications functions in the
  1260.   BIOS uses the polled method.  In this approach, the CPU is  typically  in  a
  1261.   loop asking the UART over and over again if it has a byte ready. If it does,
  1262.   the  polling  code  returns the byte.  But, if the next byte comes in before
  1263.   the polling code is executing again, then that byte is lost.
  1264.  
  1265.   In the interrupt driven approach (used by PCLVBW for incoming data), when  a
  1266.   byte  is  received by the UART, an interrupt is generated and the "Interrupt
  1267.   Service Routine"  (ISR)  is  executed  immediately,  suspending  temporarily
  1268.   whatever  else is executing. The ISR then moves the byte to a buffer so that
  1269.   your application program can later read it. Refer to  Section  6.6  and  6.7
  1270.   entitled  "RS232  Signals"  and  "National  8250,  16450, and 16550
  1271.   UARTs" for further information on these topics.
  1272.  
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  PCLVBW Users Manual                                               Page 19
  1293.   6.2 Standard Port Addresses
  1294.  
  1295.  
  1296.   There  are  a  few  things to know about how serial communications ports are
  1297.   used by IBM PC/XT/AT and compatible computers.  The  standard  IBM  PC/XT/AT
  1298.   configuration values are as follows:
  1299.  
  1300.   Port    Reg.   IRQ  Vector
  1301.   COM1    3F8H    4     12
  1302.   COM2    2F8H    3     11
  1303.   COM3    3E8H    4     12
  1304.   COM4    2E8H    3     11
  1305.  
  1306.   (Refer to your DigiBoard manual for DigiBoard addresses, or your BOCA  board
  1307.   manual for BOCA port addresses).
  1308.  
  1309.   PCLVBW assumes the above values.  If necessary, the UART base address can be
  1310.   changed by SioUART, and IRQ lines can be re-assigned  by  SioIRQ.   Remember
  1311.   that  each  port to be used concurrently must have a unique IRQ line.  Refer
  1312.   to the PCLVBW Reference Manual for specific details.
  1313.  
  1314.   When installing new  communications  cards,  the  following  guidelines  are
  1315.   recommended:
  1316.  
  1317.   (1)  Be  sure to read the documentation for the hardware you are installing.
  1318.   Pay special attention to UART base addresses and IRQ lines, particularly  if
  1319.   trying to set up a non-standard configuration.
  1320.  
  1321.   (2)  If  you  have  a  choice in base addresses and IRQ lines, always choose
  1322.   standard values as defined above.
  1323.  
  1324.   (3) The first port should be COM1, the second COM2, etc.  Do NOT  skip  over
  1325.   any port.
  1326.  
  1327.   (4)  Use SioUART to zero all unused ports (for example, call SioUART(COM4,0)
  1328.   if there is no COM4 port installed).
  1329.  
  1330.   (5) Be carefull not to configure two ports for the  same  address.  This  is
  1331.   easier to do than you may believe.
  1332.  
  1333.   (6)  Choose  an  external  modem over an internal one.  It is much easier to
  1334.   debug problems with an external modem than an internal one.
  1335.  
  1336.   (7) Select hardware flow control (RTS/CTS) if flow control is  required  and
  1337.   hardware flow control is not the default.
  1338.  
  1339.   (8)  Always  test your port as soon as it is installed. Try several programs
  1340.   that use the communications ports.
  1341.  
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  PCLVBW Users Manual                                               Page 20
  1361.   6.3 Running 3 or 4 Ports Concurrently
  1362.  
  1363.  
  1364.   PCLVBW supports up to 4 serial ports running concurrently (more if you  have
  1365.   a  DigiBoard  or BOCA board).  One free interrupt for each port is required.
  1366.   Refer to the next section if you have a DigiBoard or BOCA board.
  1367.  
  1368.   Interrupts  IRQ4  and  IRQ3  are  dedicated to the communications ports in a
  1369.   standard IBM PC/XT/AT configuration.  IRQ4 is shared between COM1  and  COM3
  1370.   while IRQ3 is shared between COM2 and COM4.  This means that you can run two
  1371.   ports simultaneously provided that they don't share an interrupt.
  1372.  
  1373.   Suppose that you wish to run 3 ports simultaneously. To begin, you must have
  1374.   3  serial  UARTs  installed  on your computer.  Assume, for purposes of this
  1375.   discussion, that COM1 is installed on your motherboard, and  that  you  have
  1376.   purchased a new 2 port serial communications board.
  1377.  
  1378.   You  should  be able to configure the first serial board port as COM2, which
  1379.   uses IRQ3.  Refer to the manual that came with your serial board.
  1380.  
  1381.   In order to run the third serial port concurrently with the  first  two,  an
  1382.   unused  interrupt  must be found.  If your serial card can use only IRQ3 and
  1383.   IRQ4, then there is no way to run a third line since IRQ4 and IRQ3 are  used
  1384.   for COM1 and COM2.
  1385.  
  1386.   However,  many serial cards can use other IRQs, typically IRQ2 through IRQ5.
  1387.   Since IRQ5 is normally used  for  a  second  printer  port,  it  is  a  good
  1388.   candidate  for  COM3.  To use IRQ5 for the third serial port, first set your
  1389.   serial card to use IRQ5 for COM3 (refer to your serial card manual) and then
  1390.   add the following line to your applications code before calling SioReset:
  1391.  
  1392.          SioIRQ(COM3,IRQ5);
  1393.  
  1394.   Don't forget to disable any device that might use IRQ5,  such  as  a  second
  1395.   printer  port  or  a  music  card.   Unfortunately,  there is no easy way to
  1396.   determine that you have no conflicts until you actually attempt to  use  the
  1397.   IRQ.  If  there  are  conflicts, your system will probably hang and you will
  1398.   have to reboot.
  1399.  
  1400.   To run a fourth serial port, another  free  IRQ  must  be  found.   On  some
  1401.   systems, IRQ7 can be used. To use IRQ7 for the fourth serial port, first set
  1402.   your serial card to use IRQ7 for COM4 and then add:
  1403.  
  1404.          SioIRQ(COM4,IRQ7);
  1405.  
  1406.   To summarize, your serial card must be able to  generate  the  correct  IRQ,
  1407.   which  is not already being used. Refer to the entry for the SioIRQ function
  1408.   in the PCLVBW Reference Manual.
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  PCLVBW Users Manual                                               Page 21
  1429.   6.4 Using Multiport Cards
  1430.  
  1431.  
  1432.   The PCLVBW library supports the dumb Digiboard (PC/4 & PC/8)  and  the  dumb
  1433.   BOCA board (BB1004, BB1008, and BB2016).
  1434.  
  1435.   6.4.1 The DigiBoard
  1436.  
  1437.   In  order  to  use  the  DigiBoard,  you  must  configure  PCLVBW  using the
  1438.   SioPorts(), SioUART(), and SioIRQ() functions.
  1439.  
  1440.   Your PCs ports must be partitioned into "standard" PC ports  and  dumb  card
  1441.   ports.  Remember that standard PC ports cannot share IRQs like the DigiBoard
  1442.   (or  BOCA  board)  can. If you are using IRQ4 and IRQ3 for standard PC ports
  1443.   COM1 and COM2, then you cannot use either for DigiBoard ports (try  IRQ5  or
  1444.   IRQ7).
  1445.  
  1446.   Suppose that COM1 through COM2 are standard PC ports (using IRQ4  and  IRQ3)
  1447.   and  you  have  installed  a  PC/8  DigiBoard  that you wish to use for COM3
  1448.   through COM10 using interrupt line IRQ5.  You choose to use the  recommended
  1449.   DigiBoard UART addresses starting at 0x100:
  1450.  
  1451.        DEFINT A-Z
  1452.  
  1453.        RC = SioPorts(8,COM1,&H140,DIGIBOARD)  'COM1 = 1st BOCA port
  1454.        Address = &H100                        '1st BOCA UART address
  1455.        FOR Port=COM1 TO COM8                  'look at each port
  1456.          RC = SioUART(Port,Address)           'set the UART address
  1457.          Address = Address + 8                'compute next address
  1458.          RC = SioIRQ(Port,IRQ5)               'set the BOCA IRQ
  1459.        NEXT I
  1460.  
  1461.   The DigiBoard uses 0x140 for the status address for odd interrupts and 0x141
  1462.   for even interrupts.
  1463.  
  1464.   Digiboard  may  be  contacted  at  6400 Flying Cloud Drive, Eden Prairie, MN
  1465.   55344.  Telephone 612-943-9020 or FAX 612-943-5398.
  1466.  
  1467.   6.4.2 The BOCA Board
  1468.  
  1469.   As with the DigiBoard, you must  configure  PCLVBW  before  using  the  BOCA
  1470.   board.
  1471.  
  1472.   For  example,  to  configure the BOCA BB2016 to use COM1 to COM16, with base
  1473.   addresses starting at 0x100 and IRQ5:
  1474.  
  1475.        DEFINT A-Z
  1476.        RC = SioPorts(16,COM1,&H107,BOCABOARD) 'COM1 = 1st BOCA port
  1477.        Address = &H100                        '1st BOCA UART address
  1478.        FOR Port=COM1 TO COM16                 'look at each port
  1479.          RC = SioUART(Port,Address)           'set the UART address
  1480.          Address = Address + 8                'compute next address
  1481.          RC = SioIRQ(Port,IRQ5)               'set the BOCA IRQ
  1482.        NEXT I
  1483.  
  1484.   BOCA may be contacted at BOCA Research, Inc., 6413  Congress  Avenue,  Suite
  1485.   130, Boca Raton, FL 33487.  Phone 407-241-8088, FAX 407-997-0918.
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  PCLVBW Users Manual                                               Page 22
  1497.   6.5 Transmitter Interrupts
  1498.  
  1499.  
  1500.   Transmitter interrupts are supported by the library.  Separate libraries are
  1501.   provided,  one  with  transmitter  interrupts enabled and one without.  When
  1502.   transmitter interrupts are NOT enabled, the following logic occurs everytime
  1503.   you call SioPutc():
  1504.  
  1505.    1. Wait for transmit buffer to become empty. The transmit
  1506.       buffer may not be empty if the previous transmit is not
  1507.       completed (the UART breaks down the byte & sends 1 bit
  1508.       at a time).
  1509.  
  1510.    2. When the transmit buffer is empty, the byte from the
  1511.       SioPutc() call is loaded into the transmit buffer and
  1512.       control is returned to the caller.
  1513.  
  1514.   Note that you can not write to the UART any faster than the UART baud rate.
  1515.  
  1516.   When transmitter interrupts are enabled, the byte from SioPutc() is put into
  1517.   a previously prepared (by SioTxQue) transmitter queue. The interrupt service
  1518.   routine fetches bytes from this queue as soon as the previous byte has  been
  1519.   sent.
  1520.  
  1521.   While  you can now call SioPutc() faster than the baud rate, bytes are still
  1522.   transmitted at the given baud rate.
  1523.  
  1524.   Transmitter  interrupts  are generally preferrable in Windows , although not
  1525.   necessary. Transmitter interrupts are better not enabled if  an  application
  1526.   will be doing little or no serial transmission.
  1527.  
  1528.   An   application  can  determine  at  runtime  if  the  PCLVBW  library  has
  1529.   transmitter interrupts enabled by  calling  SioInfo(ASC("I")).   A  non-zero
  1530.   return value indicates that transmitter interrupts are enabled.
  1531.  
  1532.   A transmit buffer must be set up using SioTxBuf  if  transmitter  interrupts
  1533.   are  enabled,  otherwise a transmit buffer is not required. See the programs
  1534.   SIMPLE and LOGIN for an example.
  1535.  
  1536.   The  default  library  (PCLVBW.DLL)  has  transmitter  interrupts  enabled.
  1537.   PCLVBW1.DLL is the library with transmitter interrupts disabled.
  1538.  
  1539.  
  1540.  
  1541.  
  1542.  
  1543.  
  1544.  
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  PCLVBW Users Manual                                               Page 23
  1565.   6.6 RS-232 Signals
  1566.  
  1567.  
  1568.   RS-232  is  the  name  of the serial data interface standard used to connect
  1569.   computers to modems.  Most IBM compatible computers are built with at  least
  1570.   one serial port and use either DB9 (9 pin) or DB25 (25 pin) connectors.
  1571.  
  1572.   A  summary  of  these  pins  and  their function follows.  For more detailed
  1573.   information, refer to one of the many books dealing with RS-232 interfacing.
  1574.  
  1575.   Signal Ground Pin 7 (DB25), Pin 5 (DB9)
  1576.  
  1577.   The SG line is used  as  the  common  signal  ground,  and  must  always  be
  1578.   connected.
  1579.  
  1580.   Transmit Data Pin 2 (DB25), Pin 3 (DB9)
  1581.  
  1582.   The TX line is used to carry data from the computer to the modem.
  1583.  
  1584.   Receive Data Pin 3 (DB25), Pin 2 (DB9)
  1585.  
  1586.   The RX line is used to carry data from the modem to the computer.
  1587.  
  1588.   Data Terminal Ready Pin 20 (DB25), Pin 4 (DB9)
  1589.  
  1590.   The  DTR  line is used by the computer to signal the modem that it is ready.
  1591.   DTR should be set high when talking to a modem.
  1592.  
  1593.   Data Set Ready Pin 6 (DB25), Pin 6 (DB9)
  1594.  
  1595.   The DSR line is used by the modem to signal the computer that it is ready.
  1596.  
  1597.   Request to Send Pin 4 (DB25), Pin 7 (DB9)
  1598.  
  1599.   The RTS line is used to "turn the line around" in half  duplex  modems,  and
  1600.   for hardware flow control in most modems that require flow control.
  1601.  
  1602.   Clear to Send Pin 5 (DB25), Pin 8 (DB9)
  1603.  
  1604.   The  CTS  line  is used to "turn the line around" in half duplex modems, and
  1605.   for hardware flow control in most modems that require flow control.
  1606.  
  1607.   Data Carrier Detect Pin 8 (DB25), Pin 1 (DB9)
  1608.  
  1609.   The DCD line is used by the modem to signal the computer that a data carrier
  1610.   signal is present.
  1611.  
  1612.   Ring Indicator Pin 22 (DB25), Pin 9 (DB9)
  1613.  
  1614.   The RI line is asserted when a 'ring' occurs.
  1615.  
  1616.  
  1617.  
  1618.  
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.  
  1627.  
  1628.  
  1629.  
  1630.  
  1631.  
  1632.  PCLVBW Users Manual                                               Page 24
  1633.   6.7 National 8250, 16450, and 16550 UARTs
  1634.  
  1635.  
  1636.   The Personal Communications  Library  is  based  on  the  standard  National
  1637.   8250,  16450,  and 16550 UARTs. The 8250 was the original UART used
  1638.   in the IBM PC, whereas the 16450 is a faster version found on most 286 &  up
  1639.   machines. The 16550 contains a 16 byte FIFO to further reduce communications
  1640.   overhead. These UARTs consists of 8 register ports as follows:
  1641.  
  1642.   Offset    R/W   Register
  1643.     0       R/W   Receiver (read) / Transmitter (write)
  1644.     1       R/W   Interrupt Enable (read)
  1645.     2       R     Interrupt Identification
  1646.     2       W     FIFO control (16550 only)
  1647.     3       R/W   Data Format (Line Control)
  1648.     4       R/W   RS-232 (Modem) Control
  1649.     5       R/W   Line Status
  1650.     6       R/W   RS-232 (Modem) Status
  1651.     7       R/W   Not used.
  1652.  
  1653.   For  the standard PC ports (not DigiBoard or BOCA ports), the UART registers
  1654.   are based at 3F8h (COM1), 2F8h (COM2), 3E8h (COM3), and 2E8h  (COM4).   COM1
  1655.   and COM3 share interrupt request line IRQ4 while COM2 and COM4 share request
  1656.   line  IRQ3.   This  means  that  COM1  and  COM3 can't be used concurrently.
  1657.   Similarly for COM2 and COM4.
  1658.  
  1659.   If you have a DigiBoard (or BOCA board) installed, you will have 4  or  more
  1660.   additional  ports  using  16450 or 16550 UARTS.  The default DigiBoard
  1661.   and BOCA board ports are located at 100h, 108h, 110h,  etc.  Refer  to  your
  1662.   DigiBoard (or BOCA board) manual.
  1663.  
  1664.   Four  sources  of  interrupts  are  possible  with  the  8250 and 16550: (1)
  1665.   receiver error or BREAK, (2) receiver data ready, (3) ready to transmit, and
  1666.   (4) RS232 input.   These  four  sources  of  interrupts  are  summarized  as
  1667.   follows:
  1668.  
  1669.   Source of Interrupt        Action Required to Clear
  1670.   Receiver error or BREAK.   Read Line Status register.
  1671.   Receiver data.             Read data from data register.
  1672.   Transmitter Buffer Empty.  Write to data register or read IID reg.
  1673.   RS232 input.               Read Modem Status register.
  1674.  
  1675.   However,  PCLVBW  only enables the receiving data interrupt. This means that
  1676.   interrupts can only be caused by incoming data.
  1677.  
  1678.   If  you  are  not  familiar with the 8250, several good books are available.
  1679.   Refer to Section 6.0 Serial Communications for recommendations.  Although  a
  1680.   knowledge of the 8250 is not necessary to use PCLVBW, a general knowledge of
  1681.   the theory of asynchronous serial communications is recommended.
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  PCLVBW Users Manual                                               Page 25
  1701.   6.8 Register Summary
  1702.  
  1703.  
  1704.   REG 0 : Data Register
  1705.  
  1706.   Reading  from  the  data  register  fetches  the next input byte, once it is
  1707.   ready.  Writing to the data register transmits the byte written to  it  over
  1708.   the serial line.
  1709.  
  1710.   REG 1 : Interrupt Enable 
  1711.  
  1712.   The  Interrupt Enable register enables each of four types of interrupts when
  1713.   the appropriate bit is set to a one.
  1714.  
  1715.   bit 3 : Enable interrupt on RS232 input.
  1716.   bit 2 : Enable interrupt on receiver error or break.
  1717.   bit 1 : Enable interrupt on transmitter buffer empty (TBE).
  1718.   bit 0 : Enable interrupt on received data (RxRDY).
  1719.  
  1720.   REG 2 : Interrupt Identification (IID)
  1721.  
  1722.   Reading  the Interrupt Identification (read only) register once an interrupt
  1723.   has occurred identifies the interrupt as follows:
  1724.  
  1725.   Bit 2  Bit 1  Bit 0  Priority    Interrupt
  1726.     0      0      1      none      none
  1727.     1      1      0      0 (high)  Serialization or break.
  1728.     1      0      0      1         Received data.
  1729.     0      1      0      2         Transmitter Buffer Empty.
  1730.     0      0      0      3 (low)   RS232 Input.
  1731.  
  1732.   In the INS16650, REG 2 (write only)  is  also  the  FIFO  control  register.
  1733.   Writing bits 6 & 7 will set the FIFO trigger level (number of bytes received
  1734.   before an interrupt is generated).
  1735.  
  1736.   Bit 7  Bit 6   Trigger             Bit 7  Bit 6   Trigger
  1737.    0      0      1 byte               1      0      8 bytes
  1738.    0      1      4 bytes              1      1      14 bytes
  1739.  
  1740.   REG 3 : Line Control
  1741.  
  1742.   RS232 line parameters are selected by writing to this register.
  1743.  
  1744.   bit 7   : DLAB = 0
  1745.   bit 6   : BREAK on(1), off(0).
  1746.   bits 5-3: Parity None(000),ODD(001),EVEN(011),MARK(101),SPACE(111)
  1747.   bit 2   : One stop bit(0), two stop bits(1).
  1748.   bits 1-0: Data bits = 5 (00), 6(01), 7(10), 8(11).
  1749.  
  1750.   When  the Divisor Latch Access Bit (DLAB) is 1, registers 0 and 1 become the
  1751.   LS and MS bytes of the Baud Rate Divisor registers.
  1752.  
  1753.   Baud   Divisor      Baud  Divisor      Baud  Divisor
  1754.    300    0180        4800   0018       38400   0003
  1755.   1200    0060        9600   000C       57600   0002
  1756.   2400    0030       19200   0006      115200   0001
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  PCLVBW Users Manual                                               Page 26
  1769.   REG 4 : Modem Control
  1770.  
  1771.   RTS, DTR, loopback testing, and  General  Purpose  Outputs  #1  and  #2  are
  1772.   controlled by the Modem Control register as follows:
  1773.  
  1774.   bit 4 : Enable local loopback.
  1775.   bit 3 : Enable GP02. Necessary for 8250 interrupts.
  1776.   bit 2 : Enable GP01.
  1777.   bit 1 : Set / clear RTS.
  1778.   bit 0 : Set / clear DTR.
  1779.  
  1780.   REG 5 : Line Status
  1781.  
  1782.   Reading  the  Line Status register provides status information as follows (1
  1783.   for TRUE, 0 for FALSE) :
  1784.  
  1785.   bit 6 : Transmitter Empty.
  1786.   bit 5 : Transmitter Buffer Empty (TBE).
  1787.   bit 4 : BREAK detect.
  1788.   bit 3 : Framing error.
  1789.   bit 2 : Parity error.
  1790.   bit 1 : Overrun error.
  1791.   bit 0 : Data Ready.
  1792.  
  1793.   REG 6 : Modem Status
  1794.  
  1795.   Reading the Modem Status register provides the following status  information
  1796.   (1 for TRUE, 0 for FALSE) :
  1797.  
  1798.   bit 7 : DCD status.
  1799.   bit 6 : RI status.
  1800.   bit 5 : DSR status.
  1801.   bit 4 : CTS status.
  1802.   bit 3 : Delta DCD status.
  1803.   bit 2 : Delta RI status.
  1804.   bit 1 : Delta DSR status.
  1805.   bit 0 : Delta CTS status.
  1806.  
  1807.   The  delta  bits  (bits 0 through 3) are set whenever one of the status bits
  1808.   (bits 4 through 7) changes (from 0 to 1 or from 1 to 0) since the last  time
  1809.   that  the  Modem Status register was read. Reading the Modem Status register
  1810.   clear the delta bits.
  1811.  
  1812.   REG 7 : Scratch Register
  1813.  
  1814.   There is no function associated with register 7.  It does not exist in early
  1815.   versions of the 8250.
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  PCLVBW Users Manual                                               Page 27
  1837.   8.0 Legal Issues
  1838.  
  1839.   8.1 Registration
  1840.  
  1841.  
  1842.   If you wish to register the PCLVBW library, please send $75 plus $5 S&H ($10
  1843.   outside of North America) to:
  1844.  
  1845.            MarshallSoft Computing, Inc.
  1846.            Post Office Box  4543
  1847.            Huntsville AL 35815
  1848.  
  1849.   Multiple copies are available: The first copy is $75. Copies 2 through 5 are
  1850.   $60 each. Copies 6 through 10 are $45 each. Copies 11 and up are $30 each. A
  1851.   site license is  also  available  for  $495  (includes  5  sets  of  printed
  1852.   documentation). We pay shipping on multiple copy orders.
  1853.  
  1854.   We accept American Express, VISA, and Mastercard (account number, expiration
  1855.   date,  exact  name  on  your  card,  and complete billing address required),
  1856.   checks in US dollars  drawn  on  a  US  bank,  purchase  orders  (POs)  from
  1857.   recognized  US  schools  and  companies  listed in Dun & Bradstreet, and COD
  1858.   (street address and phone number required) within the USA (plus a $4.50  COD
  1859.   charge).
  1860.  
  1861.   You  can  also order PCLVBW from The Public Software Library (PSL) with your
  1862.   MC, Visa, AmEx, or Discover card by  calling  800-242-4PSL  (from  overseas:
  1863.   713-524-6394)  or  by  FAX  at 713-524-6398 or by CompuServe at [71355,470].
  1864.   THESE NUMBERS ARE FOR ORDERING ONLY. The product number for PCLVBW is 11499.
  1865.   (Specify VisualBASIC/Windows when  you  call).  Please  have  your  shipping
  1866.   address and credit card billing address ready.
  1867.  
  1868.   If  you wish to update from an older version of PCLVBW, send $20 plus $5 S&H
  1869.   ($10 outside of North  America).   Updates  must  be  ordered  directly  from
  1870.   MarshallSoft Computing.
  1871.  
  1872.   The registered package includes:
  1873.  
  1874.   o  Assembler source code for the communications library.
  1875.   o  C source code for the modem I/O library.
  1876.   o  Printed Users and Reference Manuals.
  1877.   o  Telephone, email, FAX, and BBS support for one year.
  1878.  
  1879.   Print the file INVOICE.DOC if an invoice is needed. The registered user will
  1880.   receive  the  latest  version  of  PCLVBW  shipped  by two day priority mail
  1881.   (packet airmail overseas).  A 3.5"  diskette  is  provided  unless  a  5.25"
  1882.   diskette is requested.
  1883.  
  1884.  
  1885.  
  1886.  
  1887.  
  1888.  
  1889.  
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  PCLVBW Users Manual                                               Page 28
  1905.   8.2 License
  1906.  
  1907.  
  1908.   MarshallSoft Computing, Inc. grants the registered user of PCLVBW the  right
  1909.   to  use one copy of the PCLVBW library (in object form) on a single computer
  1910.   in the development of any software product (other  than  libraries  such  as
  1911.   PCLVBW).   The user may not use the library on more than one computer at the
  1912.   same time.  The source code for the library (PCLVBW.ASM) is  copyrighted  by
  1913.   MarshallSoft Computing and may not be released in whole or in part.
  1914.  
  1915.   Products  developed  using PCLVBW can include the object form of the library
  1916.   and may be distributed without any royalty.
  1917.  
  1918.  
  1919.   8.3 Warranty
  1920.  
  1921.  
  1922.   MARSHALLSOFT COMPUTING, INC.  DISCLAIMS  ALL  WARRANTIES  RELATING  TO  THIS
  1923.   SOFTWARE,  WHETHER  EXPRESSED  OR  IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
  1924.   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR  PURPOSE,
  1925.   AND  ALL  SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER
  1926.   MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN  INVOLVED  IN  THE
  1927.   CREATION,  PRODUCTION,  OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY
  1928.   INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT  OF  THE  USE  OR
  1929.   INABILITY  TO  USE  SUCH  SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC.  HAS
  1930.   BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL
  1931.   MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH  DAMAGES  EVER  EXCEED
  1932.   THE  PRICE  PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM
  1933.   OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY
  1934.   AND PERFORMANCE OF THE SOFTWARE.
  1935.  
  1936.   Some states do not allow  the  exclusion  of  the  limit  of  liability  for
  1937.   consequential  or  incidental damages, so the above limitation may not apply
  1938.   to you.
  1939.  
  1940.   This agreement shall be governed by the laws of the  State  of  Alabama  and
  1941.   shall  inure  to  the  benefit  of  Marshallsoft  Computing,  Inc.   and any
  1942.   successors, administrators, heirs and  assigns.  Any  action  or  proceeding
  1943.   brought  by either party against the other arising out of or related to this
  1944.   agreement shall be brought only in a STATE or  FEDERAL  COURT  of  competent
  1945.   jurisdiction  located in Madison County, Alabama. The parties hereby consent
  1946.   to in personam jurisdiction of said courts.
  1947.  
  1948.  
  1949.  
  1950.  
  1951.  
  1952.  
  1953.  
  1954.  
  1955.  
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  PCLVBW Users Manual                                               Page 29
  1973.   9.0 Summary
  1974.  
  1975.  
  1976.   9.1 Revision History
  1977.  
  1978.  
  1979.   Version 1.0 - 10 February 1996
  1980.  
  1981.  
  1982.   This  is  the  first  release  of  the Visual BASIC / Windows version of our
  1983.   library. It uses the common assembler language library used in  all  of  our
  1984.   Windows and DOS communications library products.
  1985.  
  1986.  
  1987.    9.2 Function Summary
  1988.  
  1989.  
  1990.   Refer to the PCLVBW Reference Manual (PCLVBW.REF) for  detailed  information
  1991.   on  the  communications  and  support functions.  A one line summary of each
  1992.   function follows:
  1993.  
  1994.  
  1995.   SioBaud     Sets the baud rate of the selected port.
  1996.   SioBrkSig   Asserts, cancels, or detects BREAK signal.
  1997.   SioCTS      Reads the Clear to Send (CTS) modem status bit.
  1998.   SioDCD      Reads the Data Carrier Detect (DCD) modem status bit.
  1999.   SioDone     Terminates further serial processing.
  2000.   SioDSR      Reads the Data Set Ready (DSR) modem status bit.
  2001.   SioDTR      Set, clear, or read the Data Terminal Ready (DTR) bit.
  2002.   SioFIFO     Sets the interrupt level for the 16550.
  2003.   SioFlow     Enables / disables hardware flow control.
  2004.   SioGetc     Reads the next character from the serial line.
  2005.   SioGetDiv   Reads the baud rate divisor registers.
  2006.   SioKeyPress Detects if keyboard has been pressed.
  2007.   SioKeyRead  Reads the keyboard.
  2008.   SioInfo     Returns library version number & memory model.
  2009.   SioIRQ      Assigns an IRQ line to a port.
  2010.   SioLine     Reads the line status register.
  2011.   SioLoopBack Performs a UART loopback test.
  2012.   SioModem    Reads the modem status register.
  2013.   SioParms    Sets parity, stop bits, and word length.
  2014.   SioPorts    Sets # ports, 1st DigiBoard / BOCA port & status reg.
  2015.   SioPutc     Transmit a character over a serial line.
  2016.   SioRead     Reads any of 7 UART ports.
  2017.   SioReset    Initialize a serial port for processing.
  2018.   SioRI       Reads the Ring Indicator (RI) modem status bit.
  2019.   SioRTS      Sets, clears, or reads the Request to Send (RTS) line.
  2020.   SioRxBuf    Sets up receive buffer.
  2021.   SioRxClear  Clears the receive buffer.
  2022.   SioRxQue    Returns the number of characters in the receive queue.
  2023.   SioTxBuf    Sets up transmit buffer.
  2024.   SioTxClear  Clears the transmit buffer.
  2025.   SioTxFlush  Flushes the transmit buffer.
  2026.   SioTxQue    Returns the number of characters in the transmit queue.
  2027.   SioUART     Sets the UART base address.
  2028.   SioUnGetc   "Un-gets" (puts back) a specified character.
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  PCLVBW Users Manual                                               Page 30
  2041.   9.3 Further Reading
  2042.  
  2043.  
  2044.   The best way to learn about serial communications is to read a good book  on
  2045.   the subject. Several good texts are available.  Two that I like are:
  2046.  
  2047.   (1) C  Programmers's  Guide to Serial Communications by Joe Campbell (SAMS)
  2048.   (2) Mastering Serial Communications by Peter Gofton (SYBEX).
  2049.  
  2050.  
  2051.   10.0 Other MarshallSoft Computing Products
  2052.  
  2053.  
  2054.   MarshallSoft Computing also makes communication libraries for Visual BASIC /
  2055.   DOS  (PCL4VB),  Power  BASIC  (PCL4PB),  C/DOS  (PCL4C),  C/Windows (PCL4W),
  2056.   Pascal/DOS (PCL4P), Delphi (PCL4D).
  2057.  
  2058.   We  also  will  be releasing a communications library that uses the build-in
  2059.   Windows  communications  functions.  It  will be limited to 9 ports at 19200
  2060.   baud.
  2061.  
  2062.  
  2063.  
  2064.  
  2065.  
  2066.  
  2067.  
  2068.  
  2069.  
  2070.  
  2071.  
  2072.  
  2073.  
  2074.  
  2075.  
  2076.  
  2077.  
  2078.  
  2079.  
  2080.  
  2081.  
  2082.  
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.  
  2090.  
  2091.  
  2092.  
  2093.  
  2094.  
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.  PCLVBW Users Manual                                               Page 31
  2109.